ソースコードからApple標準スタイルのAPIドキュメントを生成するappledocの書き方

平井祐樹

2013.06.12

この記事は公開されてから1年以上経過しています。情報が古い可能性がありますので、ご注意ください。

appledoc！

Objective-CのソースコードからAPIドキュメントを生成するツールとしてはHeaderDocやDoxygenなどがありますが、その中でもApple標準スタイルのようなおしゃれなAPIドキュメントを生成してくれるappledocを解説したいと思います。

appledocのいいところは何と言ってもApple標準スタイルでのドキュメントがお手軽に作成できることです。他のツールでも同じようにAPIドキュメントを作成できますが、iOS開発者にとって見慣れたデザインでドキュメントを生成してくれるのは非常にありがたいですね。また導入も非常に簡単で、Xcode内からAPIリファレンスとして参照できるDocSetも生成してくれます。

このappledocですが、導入までの簡単な流れを解説しているサイトは、appledocでドキュメント生成 #iOS #AdventCalendar - Qiita [キータ]などとても分かりやすいものが既に公開されていますが、詳細な使い方が記述されているサイトがなかなかないので、今回は公式ドキュメントに沿ってコメントの書き方ついて解説していきます。

appledocの導入

上で説明した通り、appledocでドキュメント生成 #iOS #AdventCalendar - Qiita [キータ]に導入から簡単な使い方まで詳しく書かれているので、そちらを参考にappledocを準備しておいてください。

サンプルプロジェクトの作成

本記事では以下の環境を前提に説明します。

Mac OS X 10.8 Moutain lion
Xcode 4.6.2
iOS SDK 6.1

プロジェクトの作成

ドキュメント生成の対象となるプロジェクトを作成します。XcodeよりSingle View Applicationを選択し、以下の内容でプロジェクトを作成しましょう。

項目	設定値
Product Name	AppledocSample
Organization Name	自分の名前（サンプルなのでテキトー）
Company Identifier	会社名（サンプルなのでテキトー）
Class Prefix	なし
Devices	iPhone
Use Storyboards	チェックする（ストーリーボードを使用）
Use Automatic Reference Counting	チェックする（ARC有効）
Include Unit Tests	チェックしない（unit testのターゲットを含まない）

サンプルクラスの作成

プロジェクトを作成したら、コメントを試すためのクラスとしてNSObjectを継承したSampleObjectを作成しましょう。

コメントの書式

appledocでは、以下で紹介する特別な書式で書かれたコメントからドキュメントを抽出します。また、もともとHeaderDocやDoxygenの書式で書かれた書式にも対応しているため、簡単に移植できます。

複数行のコメント

appledocでは「/** コメント */」のように/(スラッシュ)１つと*(アスタリスク)２つで始まり、*(アスタリスク)１つと/(スラッシュ)１つで終わるコメントを解析対象とします。

/** コメントをかくぜぇ */

試しにSampleObject.hのクラス定義の上に以下のように書いてみましょう。

SampleObject.h

#import <Foundation/Foundation.h>

/** コメントをかくぜぇ */
@interface SampleObject : NSObject

@end

変更したらターミナルを開いてAppledocSampleのディレクトリに移動し、以下のコマンドを実行しましょう。

% cd path/to/AppledocSample
% appledoc --project-name AppledocSample --project-company Classmethod --create-html --no-create-docset --output ./docs/ .

すると、プロジェクトディレクトリ以下にdocs/htmlディレクトリが作成されます。この中にindex.htmlが作成されているので、これをブラウザで開いてみましょう。

以下のような画面が表示されるので、作成したSampleObjectをクリックします。

すると、先ほど記述したコメントが表示されるはずです。

以降はこの方法で確認していきますので、適宜ドキュメントを生成して出力を確認してみてください！

さて、話を戻しますが、改行すれば当然複数行で書くことができます。

/**
 コメントをかくぜぇ
 複数行にしたぜぇ
 */

以下のように行頭に空白と*(アスタリスク)を付与することもできます。この場合、この「 * 」はドキュメント生成時に無視されます。

/** 
 * 複数行でコメントを
 * かいちゃうんだぜぇ
 */

また、HeaderDoc形式のコメントも対象になります。

/*! コメントをかくぜぇ */

個人的には最初の書き方が好きですが、いずれにしても１つの形式で統一しておきましょう。また、上記のようにコメントを改行しても実際に出力されるドキュメントでは改行されません。

ドキュメントで改行するための書き方はこの後解説します。

単一行のコメント

appledocでは/(スラッシュ)３つで始まる単一行コメントも解析対象になります。

/// 単一行のコメントだぜぇ

但し、連続してこの形式のコメントを書くと、複数行のコメントとしてグループ化されます。

/// 単一行のコメントと見せかけて
/// 複数行かけるぜぇ

コメントレイアウト

appledocでは、コメントの書き方としてマークダウンのような構文を使用します。これにより、ソースコードの可読性をできる限り損ねないような設計になっています。まぁ、百聞は一件にしかずですので、早速どんなものがあるか見ていきましょう。

段落

段落を表すのは非常に簡単で、段落としてまとめたい行の間に空の行を挿入するだけです。先ほど、複数行のコメントを書きましたが、空行を挟まない場合は同一段落とみなされるため、実際に出力されるドキュメントは改行されなかったわけです。

/**
 １つ目の段落だぜぇ

 ２つ目の段落は
 改行しちゃうぜぇ

 そしてまた別の段落だぜぇ
 */

１つ目の段落の扱いですが、クラスコメントとメソッドコメントで少し生成される結果が変わります。試しに以下のように変更して出力結果を見てみましょう。

#import <Foundation/Foundation.h>

/**
 １つ目の段落だぜぇ
 
 ２つ目の段落は
 改行しちゃうぜぇ
 
 そしてまた別の段落だぜぇ
 */
@interface SampleObject : NSObject

/**
 １つ目の段落だぜぇ
 
 ２つ目の段落は
 改行しちゃうぜぇ
 
 そしてまた別の段落だぜぇ
 */
- (void)sampleMethod;

@end

以下のようにメソッドコメントの１つ目の段落は、短い説明文としても使用されます。このとき、長い説明文にも１段落目が残ってしまいますが、これが嫌な場合はコマンドに--repeat-first-par（--no-repeat-first-par）オプションを指定することで、解決できます。

順不同リスト

順不同リストを使用するには、リストアイテムの先頭に-(ハイフン)か+(プラス)を付与します。リストの前後には空行を入れて他の段落と分離する必要があります。

/**
 コメントだぜぇ

 - １つ目のアイテムだぜぇ
 - ２つ目のアイテムは
 改行しちゃうぜぇ
 - ３つ目のアイテムだぜぇ
 */

リストを入れ子にする場合は、以下のように子アイテムをタブかスペースでインデントするだけです。

/**
コメントだぜぇ

 - １つ目のアイテムだぜぇ
    - ネスト1だぜぇ
        - ネスト1のネスト1だぜぇ
    - ネスト2だぜぇ
 - ２つ目のアイテムだぜぇ
 */

順序付きリスト

順序付きリストの場合は、リストアイテムの先頭に1.のように数字と.(ドット)を付与します。

/**
 コメントだぜぇ
 
 1. １つ目のアイテムだぜぇ
 2. ２つ目のアイテムだぜぇ
 */

コードブロック

コードのサンプルなどを記述したい場合はコードブロックが有効です。コードブロックは該当する段落の行頭にタブかスペース４つ を付与します。

/**
 １つ目の段落だぜぇ

 	コードブロックのコメントだぜぇ
 	見やすいぜぇ

 ２つ目の段落コメントだぜぇ
 */

重要情報ブロック

重要な情報を表すブロックを使用するには、行の先頭に@warningディレクティブを付与します。

/**
 １つ目の段落だぜぇ
 
 @warning このブロックは重要な情報が書かれているぜぇ
 当然複数行に分けて書けるぜぇ
 
 このディレクティブを使用すると以降の段落もこのブロックに含まれてしまうぜぇ
 */

ここで１つ注意しなければならないのが、@warningディレクティブを使用すると、以降の段落もこのブロックに含まれてしまうことです。なので、このディレクティブを使用する際はコメントの末尾に記述するなど工夫して使用しましょう。

バグ情報ブロック

バグ情報を表すブロックを使用するには、行の先頭に@bugディレクティブを付与します。

/**
 １つ目の段落だぜぇ
 
 @warning このブロックは重要な情報が書かれているぜぇ
 当然複数行に分けて書けるぜぇ
 
 このディレクティブを使用すると以降の段落もこのブロックに含まれてしまうぜぇ
 */

@bugディレクティブも@warningディレクティブ同様の挙動となるので注意してください。

テキストの書式

あまり量はありませんが、appledocではテキストの書式を変更することができます。

強調表示

appledocでは斜体、太字、斜体＋太字の３つの強調表示が用意されています。書き方は強調したい文字を*(アスタリスク)、または_(アンダースコア)で囲むだけです。

項目	説明
斜体	テキスト（または_テキスト_）
太字	テキスト（または__テキスト__）
斜体+太字	*テキスト*（または___テキスト___）

/**
 アスタリスクでの書き方
 
 斜体：*強調表示*
 
 太字：**強調表示**
 
 斜体＋太字：***強調表示***
 
 アンダースコアでの書き方
 
 斜体：_強調表示_
 
 太字：__強調表示__
 
 斜体＋太字：___強調表示___
 */

公式ドキュメントでは、*text*で太字、_text_で斜体とも書かれていますが、どうやるかわかりませんw誰か教えてください！！

コードスパン

コメントにソースコードを記述する場合は、`(バッククォート)で囲みます。尚、コードスパン内は強調表示はできません。

/**
 コメント内にコードを書く
 
 `- (void)sampleMethod:(NSString *)sample;`
 */

リンクと相互参照

URLへのリンク

コメント内にhttp://、https://、ftp://、file://またはmailto:があれば自動的にリンクに変換されます。

/**
 コメント内にリンクを書く
 
 AWSのことならhttp://classmethod.jp!
 */

クラス・カテゴリー・プロトコルへのリンク

コメント内にクラスやカテゴリー、プロトコルの名前があると、それらがドキュメント化されている（つまりappledoc用のコメントが書かれている）場合、自動的にそのドキュメントへのリンクが生成されます。

例として、カテゴリーNSObject+SampleとプロトコルSampleProtocolを作成し、それぞれのヘッダファイルを以下のように記述してみましょう。

NSObject+Sample.h

#import <Foundation/Foundation.h>

/**
 サンプルカテゴリー
 */
@interface NSObject (Sample)

@end

SampleProtocol.h

#import <Foundation/Foundation.h>

/**
 サンプルプロトコル
 */
@protocol SampleProtocol <NSObject>

@end

これらのファイルを追加・変更したら、SampleObject.hを以下のように変更してみましょう。

#import <Foundation/Foundation.h>

/**
 コメント内に NSObject(Sample) と書くとリンクになるぜぇ

 コメント内に SampleProtocol と書くとリンクになるぜぇ
 */
@interface SampleObject : NSObject

@end

このとき、カテゴリ名やプロトコル名の前後にスペースがないとうまく抽出してくれないことがあるため、なるべくスペースを入れるようにしましょう。

ローカルメンバーへのリンク

ローカルメンバーもクラスなどと同様、ドキュメント化されていればコメント内の名前をリンクに変更してくれます。今度は、SampleObject.hを以下のように変更してみましょう。

#import <Foundation/Foundation.h>

/**
 ここにローカルメンバーを記述するとリンクになる
 
 sampleProperty
 
 sampleMethod:
 */
@interface SampleObject : NSObject

/**
 サンプルプロパティ
 */
@property NSString *sampleProperty;

/**
 サンプルメソッド
 */
- (void)sampleMethod:(NSString *)sample;

@end

外部のメンバーへのリンク

別のクラスなどで定義されたメンバーのリンクは以下のように記述します。これも上記と同様、参照先がドキュメント化されている必要があります。

SampleOtherObjectクラスを作成し、以下のように変更しましょう。

SampleOtherObject.h

#import <Foundation/Foundation.h>

/**
 その他のオブジェクト
 */
@interface SampleOtherObject : NSObject

/**
 その他のオブジェクトのサンプルメソッド
 */
@property NSString *otherProperty;

/**
 その他のオブジェクトのサンプルメソッド
 */
- (void)otherMethod;

@end

SampleObject.hを以下のように変更して、ドキュメントを生成してみましょう。

#import <Foundation/Foundation.h>

/**
 以下のように記述すると別のクラスのメンバーへのリンクが生成される
 
 [SampleOtherObject otherProperty]
 
 [SampleOtherObject otherMethod]
 */
@interface SampleObject : NSObject

@end

カスタムリンク

任意の文字をリンクにする場合は、「[表示する文字](リンク先)」のように書きます。

/**
 appledocについては[このページ](http://gentlebytes.com/appledoc/)を参照してください。
 
 [別のクラスのプロパティ]([SampleOtherObject otherProperty])
 
 [別のクラスのメソッド]([SampleOtherObject otherMethod])
 */

メソッドとプロパティの説明

メソッドとプロパティには以下の@ディレクティブを使用することができます。

項目	書き方	説明
@return	@return <description>	メソッドまたはプロパティの結果に関する説明
@param	@param <name> <description>	メソッドの引数の説明
@exception	@exception <name> <description>	発生する可能性のある例外の説明

#import <Foundation/Foundation.h>

/**
 サンプルオブジェクト
 */
@interface SampleObject : NSObject

/**
 サンプルプロパティ
 */
@property NSString *sampleProperty;

/**
 サンプルプロパティ
 
 @param sample セットする文字列
 @return 取得する文字列
 */
- (NSString *)sampleMethod:(NSString *)sample;

@end

グルーピングディレクティブ

「@name <タイトル>」を使用することでメソッドやプロパティをグループ化することができます。@nameディレクティブでまとめられたグループは生成されたHTMLドキュメントのTasksに書き出されます。@nameディレクティブを指定する場合は、個別のコメントとして書く必要があります。グループ化される範囲は、このディレクティブを含むコメント以降のメソッドがすべて対象となるので注意してください。

#import <Foundation/Foundation.h>

/**
 サンプルオブジェクト
 */
@interface SampleObject : NSObject

/// @name プロパティ

/**
 プロパティA
 */
@property NSString *propertyA;

/**
 プロパティB
 */
@property NSString *propertyB;

/// @name メソッド

/**
 メソッドA
 */
- (void)methodA;

/**
 メソッドB
 */
- (void)methodB;

@end

コメントの区切り

コメント内で任意の記号（!@#$%^&*()_=+`~,<.>/?;:'\"-）を３つ以上連続して書くと、コメント内の区切り線と見なされ無視されます。

/// ---------------------------------
/// comment
/// ---------------------------------

AFNetworkingでは、この特性を活かして上述した@nameディレクティブを以下のように書いているようです。

/// ---------------------------------
/// @name タイトル
/// ---------------------------------

まとめ

ざっと公式ドキュメントをもとにappledocのコメントの書き方をまとめてみました。APIドキュメントが納品物でなくても、こういう資料をちゃんと用意しておきましょう！

次回はappledocの設定について書きたいと思います。